Erste Schritte #

Stand: 09.04.2024

Die Kartenviewer API-Software lässt sich in wenigen Schritten einfach auf dem eigenen Server aufsetzen, ausprobieren und an eigene Bedürfnisse anpassen. Bitte folgen Sie dazu den unten stehenden Punkten.

Versionen #

Die Software liegt in zwei unterschiedlichen Ausführungen vor, einmal als Standalone und einmal als API. Die Standalone-Variante wird dann genutzt, wenn der Kartenviewer als autonomes und eigenständiges Portal fungieren soll. Die API-Version wird hingegen verwendet, wenn der Kartenviewer in ein anderes System integriert wird, bspw. um mit diesem zu interagieren oder Daten auszutauschen.

Je nach Anwendungfall muss eine andere Version heruntergeladen werden. Grundsätzlich sind die Schritte zum Aufsetzen des Viewer jedoch erst einmal gleich.

Los geht’s #

Um ein eigenes Portal aufzusetzen, laden Sie bitte eine der vorbereiteten Demoanwendungen herunter:

Standalone:
- Download als ZIP
- Download über GIT
API:
- Download als ZIP
- Download über GIT

Um das Portal zugänglich zu machen (zum Beispiel im Internet), ist es notwendig, das Portal auf einem Webserver bereitzustellen. Dazu verschieben Sie die Dateien auf Ihren Webserver (z.B. in das htdocs-Verzeichnis eines Apache-Servers).
Die heruntergeladene Anwendung enthält die Dateistruktur:

[Projektordner]
- index.html (nur API)
- index.js (nur API)
- default/
  - ressources/
    - img/
      - …
    - rest-services-internet.json
    - services-internet.json
    - style_v2.json
  - config.js
  - config.json
  - index.html (nur Standalone)
- mastercode/
  - [version]/
    - css/
      - …
    - img/
      - …
    - js/
      - …
Erläuterung

Im Projektordner befindet sich eine Beispiel-Anwendungen mit den Konfigurationsdateien config.js und config.json sowie der index.html.

Darin enthalten ist auch der Ordner ressources, der die globalen Konfigurationsdateien services.json, rest-services.json und style.json enthält sowie die benötigten Bilder (Ordner img) dieser Portalinstanz.

Der Ordner mastercode enthält die komprimierten Javascript-Dateien und die CSS-Dateien des Viewers. Im Ordner img sind die für das Portal notwenidgen Bilder abgelegt.

Sie können das Beispielportal mit folgenden URLs über einen Browser aufrufen:

Standalone
- https://[Name-des-Webservers]/[Projektordner]/default/
API
- https://[Name-des-Webservers]/[Projektordner]

Beispielanwendung anpassen #

Um das Portal zu individualisieren, sollten insbesondere folgende Dateien angepasst werden:

config.json -> Steuerung der Portaloberfläche und der angebotenen Funktionen
config.js -> Enthält grundlegende Programmparameter
services.json -> Konfiguration der zur Verfügung stehenden Dienste und Daten
rest-services.json -> Einstellung von REST-APIs
style.json: Style-Definitionen für Vektor-FeatureTypes

Die Konfigurationsmöglichkeiten für jede Datei finden Sie im linken Menübaum. Die folgende Grafik soll die Zusammenhänge zwischen den einzelnen Dateien zeigen:

Einige der Config-Dateien können global genutzt werden. Das bedeutet, diese müssen nur einmal auf dem jeweiligen Webserver exisiteren und können von beliebig vielen Anwendungen verwendet werden. Dies hat den Vorteil, dass manche Konfigurationen nur einmal vorgenommen werden müssen. Auch ein Update der Software durch den Austausch des build Ordners ist für alle Instanzen auf einfachem Wege möglich.

Aktuell bleiben #

Die Software kann durch den Austausch des builds geupdated werden. Der build befindet sich unterhalb des Ordners “mastercode” und heißt bspw. 3_0_0_kartenviewer. Der im Ordnernamen enthaltene Zeitstempel repräsentiert die Aktualität des builds. Der gesamte Ordner ist bei einem Update auszutauschen. Ebenso müssen daraufhin die Pfade zum Build in der index.html an genau drei Stellen angepasst werden, bspw. von 3_0_0_kartenviewer zu 3_0_1_kartenviewer (je nach Version des aktuellen Builds).

  <link rel="stylesheet" href="./mastercode/3_0_0_kartenviewer/css/demo-theme-less.css">
  <link rel="stylesheet" href="./mastercode/3_0_0_kartenviewer/css/masterportal.css">
  [...]
  <script type="text/javascript" src="./mastercode/3_0_0_kartenviewer/js/masterportal.js"></script>

Es ist ratsam, im Anschluss den Browsercache zu löschen, um einen sichtbaren Effekt zu erzielen.

Aktuelle builds werden in regelmäßigen Abständen auf Gitlab der LGB veröffentlicht und als ZIP-Datei bereitgestellt: Download der Builds

Für Entwickler oder Fortgeschrittene #

Um das Portal in eine eigene Website zu integrieren, müssen unten stehende Abschnitte gesetzt werden. Dies kann anhand der index.html und der config.js aus den Demoanwendungen nachvollzogen werden.

Index.html

Referenzen zu den Stylesheets des Viewers, bspw.:

  <link rel="stylesheet" href="./mastercode/3_0_0_kartenviewer/css/demo-theme-less.css">
  <link rel="stylesheet" href="./mastercode/3_0_0_kartenviewer/css/masterportal.css">

Referenzen zu den JS-Files des Viewers, bspw.:

  <script type="text/javascript" data-masterportal-config="./default/config.js"></script>
  <script type="text/javascript" src="./mastercode/3_0_0_kartenviewer/js/masterportal.js"></script>

MpConfigPath und MpMastercodePath setzen (nur API), bspw.:

  <script type="text/javascript">
    window.MpConfigPath = './';
    window.MpMastercodePath = './';
  </script>

config.js

ID des HTML DOM Elements in welchem der Viewer gerendert wird, bspw.:
```
    renderTarget: "api-target-div",
```

Pfade zur Viewer-Config, bspw.:

    portalConf: "./default/config.json",

…und zu anderen Ressourcen, bspw.:

  quickHelp: {
    imgPath: "./default/ressources/img/"
  },
  layerConf: "./default/ressources/services-internet.json",
  restConf: "./default/ressources/rest-services-internet.json",
  styleConf: "./default/ressources/style_v2.json",